AMan

A documentation browser for the Amiga

Edition 0.9b for version 1.15.

February 12, 2023

Copyright © 1994,95 Tobias Ferber, <ferber@rpk.mach.uni-karlsruhe.de>.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author.

AMan needs the following tools:

Index

GNU GENERAL PUBLIC LICENSE

@input gpl.texinfo

1 Introduction

AMan is a documentation browser for the Amiga. The idea is very simple and the implementation is simple as well: Similar to the Unix ‘man’ command it locates documentation files on your disk and spawns an external viewer. AMan uses the FDB tool by Klaus Melchior to locate the files and opens a minimal MUI window to allow a selection. See section FDB – A FindDB/UpdateDB Clone, and MUI – MagicUserInterface, for details. Of course these tools are not included in this archive.

Actually, AMan is only a quick hack. I initially wrote this tool for my private use only and I wrote it simply because I didn’t want to use MrMan anymore. Nevertheless, AMan’s concept is quite close to that of MrMan, however it makes heavily use of the said tools which are installed on my system anyway. And why should I invent the wheel over and over again? Even Stuntzi’s MagicFileRequester (MFR) makes use of FDB!

2 Installing AMan

2.1 Requirements

AMan makes heavily use of some tools which therefore must be installed on your system. Of course these tools are not included in this archive.

• Kickstart/Workbench V37 or better (including ‘More’ and ‘AmigaGuide’ or ‘MultiView’ respectively).
• The MagicUserInterface ‘MUI’. See section MUI – MagicUserInterface, for details. I tested AMan with muimaster.library version 10.0.
• The FindDB clone ‘FDB’. See section FDB – A FindDB/UpdateDB Clone, for more information. The archive ‘util/cli/FDB1_3.lha’ can be obtained (e.g. via ftp) from the Aminet. Please make sure that the ‘FDB’ executable is in your path!

Besides that, a pager like ‘Most’ or ‘MuchMore’ is recommend but not required.

2.2 Installation

Installing AMan is quite simple. You only have to copy the file ‘aman.000’ (or ‘aman.030’ if you have an MC-68030 Amiga) somewhere into your path (e.g. to ‘C:’) and rename it to ‘aman’.

Copy aman.030 TO C:aman

You might as well want to install the ldb2db tool. See section Hints & Tips, for a description. Simply copy it somewhere into your path as well.

Since AMan needs FDB, you have to install FDB if you don’t already have it. You should now make a database via UDB. Note that by default, AMan will only find files which are listed in ‘FindDB:aman.codes’. For example you might want to try the following:

UDB DB=aman help:

This will create the database ‘FindDB:aman.codes’ which contains all files in ‘help:’. If you are using AMan regularly then you might want to create a file ‘FindDB:aman.config’ which contains all the pathnames that should be scanned if you type ‘UDB DB=aman’. For example,

Echo >FindDB:aman.config "help: docs: autodocs: gnu:man/"

Before running AMan for the first time, you should make sure that MUI is installed on your system. See section MUI – MagicUserInterface, for details.

AMan is now ready for a first take-off. However, AMan will assume you want to use MultiView to view all types of documents. If you prefer some other pagers then you have to create a file ‘ENV:aman.config’. This file will be parsed by AMan via ReadArgs() in order to find out which viewer to use for the selected filename. The following example is included in this archive:

; Template: PATTERN/A,COMMAND/A

"#?.(doc|readme|txt)"  "Most *"%s*""
"#?.dvi"               "ShowDVI *"%s*""
"#?.guide"             "AmigaGuide *"%s*""
"#?"                   "MultiView *"%s*""

Empty lines and lines beginning with a semicolon ‘;’ are ignored. If no pattern matches or if ‘ENV:mrman.config’ does not exist, then AMan uses the following default:

PATTERN "#?"  COMMAND "Run <NIL: >NIL: MultiView *"%s*""

As you can see it is also possible to run viewers asynchronously. For those among you who like it even more complex: I use the following command for the pattern "#?/man[1-9]/#?.[1-9]" in my ‘aman.config’:

"NewWSH CONSOLE NIL: COMMAND *"groff -Tascii -man ***"%s***" | More*""

Example: Okay, lets try out AMan now. First we will create an FDB database for AMan from the ‘gnu:man’ directory:

UDB db=aman gnu:man/

Now let’s see whether AMan knows something about ‘gcc’.

aman gcc

AMan should now open a MUI window with a listview containing some alphabetically sorted entries like that:

gnu:man/man1/gcc.0
gnu:man/cat1/hunk2gcc.0
gnu:man/cat1/gcc.0
gnu:man/man1/gcc.1

Simply select one of those with your cursor keys and press <Return>. Your viewer should spawn and show the selected document. Press <ESC> to quit AMan.

3 Invoking AMan

3.1 Running AMan From A Shell

When invoked from within a shell, AMan uses ReadArgs() with the following template in order to parse command-line arguments:

DB=DataBase/K,H=Hide/K,E=Exact/S,P=Pattern/A/M

The ‘DB=DataBase’ parameter can be used to force AMan to use a different database than ‘FindDB:aman.codes’. For example,

aman db=find .texi

will use the default database ‘FindDB:find.codes’ to locate Texinfo files. Especially when using other databases there might also appear non-doc files in AMan’s listview which you might want to ‘Hide’… For example, to avoid the listing of icons you can invoke AMan as follows:

aman hide #?.info .dvi

This will show all the ‘.dvi’ files listed in ‘FindDB:aman.codes’ but not their icons.

Note: The patterns given to AMan are directly passed to FDB. Especially the ‘E=Exact/S’ switch is an FDB switch which allows real AmigaDOS patterns instead of only a sub-strings. Please consult your FDB documentation for details. (E.g. via ‘aman fdb’)

Note also: AMan internally makes use of the FDB switch ‘F=Files/S’. Nevertheless, FDB returns directories together with files every now and then. It’s a good idea to invoke AMan with the option ‘HIDE #?/’ as a workaround to avoid the listing of directories in AMan’s listview.

3.2 Running AMan From The Workbench

Especially when starting AMan from the Workbench the ‘Pattern’ string gadget is needed. It is active automatically when run from the Workbench, however it can be easily toggled by pressing the <TAB> key when inactive.

After pressing <Return> in the string gadget, AMan will parse it’s contents via ReadArgs() using the same template as when invoked from the shell. This guarantees full functionality without too much effort. ;-)

4 Hints & Tips

AMan always strives to allow intuitive usage. Nevertheless, some of the following hints might help you to make full profit of what AMan offers.

4.1 Extracting ‘aman.codes’ From Other Databases

Good applications, especially if they have their own drawer, want their doumentation located inside this drawer as well. This makes sense since uninstalling such an application by simply deleting it’s drawer will leave no trails. However, this way the documentation files are spread all over your disk(s) in their application drawers which makes maintaining the FDB configuration ‘aman.config’ quite hard. This is why I wrote ldb2db, a quick hack which converts a list of files into a FDB compatible database. Let me explain how to use ldb2db:

I regularly perform an UDB of my three main partitions: ‘System:’, ‘Work:’ and ‘Devel:’ via CyberCron. My ‘CronTab’ entry looks like this:

15  1    * * *    UDB System: Work: Devel:  :PRI -5

Now of course all the documentation files have already been collected into this database! The LDB tool, which is part of the FDB distribution, can be used to list the files in a database to stdout and here it comes to ldb2db:

LDB find | pgrep -x -i #?.(doc|guide) | ldb2db >FindDB:aman.codes

This extracts all ‘.doc’ or ‘.guide’ files listed in ‘FindDB:find.codes’ to ‘FindDB:aman.codes’. Of course you can also specify a larger pattern for pgrep such as

pgrep -x -i #?.(guide|doc|man|txt|readme|dvi|ps|texi|texinfo)

Note: pgrep is FreeWare and was written by Angela Schmidt, angela@rz.uni-karlsruhe.de. It is available with her pattern.library distribution.

5 FDB – A FindDB/UpdateDB Clone

The FDB and UDB tools base on FindDB and UpdateDB by Larry Phillips and Martin Steppler. UDB collects filenames from a couple of path names into a database file and FDB locates patterns in these databases. AMan uses FDB in order to retrieve the documentation files.

FDB is © Copyright 1993-94 kMel, Klaus Melchior,

Schulstraße 17, D-52156 Monschau, Germany. Phone: +49 (0)2472 4710

ADSP: kmel@eifel.adsp.sub.org
DE: kmel@eifel.fido.de
FIDO: 2:242/7.2@fidonet, 2:2452/107.2@fidonet

6 MUI – MagicUserInterface

AMan uses

MUI - MagicUserInterface

© Copyright 1993/94 by Stefan Stuntz

MUI is a system to generate and maintain graphical user interfaces. With the aid of a preferences program, the user of an application has the ability to customize the outfit according to his personal taste.

MUI is distributed as shareware. To obtain a complete package containing lots of examples and more information about registration please look for a file called ‘muiXXusr.lha’ (‘XX’ means the latest version number) on your local bulletin boards or on public domain disks.

If you want to register directly, feel free to send DM 30.– or US$ 20.– to

Stefan Stuntz

Eduard-Spranger-Straße 7

80935 München

GERMANY

Master Index

Table of Contents

About This Document

This document was generated on February 12, 2023 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on February 12, 2023 using texi2html 5.0.